package org.activequant.data.retrieval;

import org.activequant.core.domainmodel.marketscanner.ScanCriteria;
import org.activequant.core.types.TimeFrame;
import org.activequant.util.exceptions.SubscriptionException;
import org.activequant.util.pattern.events.IEventListener;

/**
* Interface that describes a subscription to live market data feed.Defines the following methods:
* <ul>
* <li>public TimeFrame getTimeFrame();</li>
* <li>public ScanCriteria getScanCriteria();</li>
* <li>public void addEventListener(IEventListener&lt;T&gt; listener);</li>
* <li>public void removeEventListener(IEventListener&lt;T&gt; listener);</li>
* <li>public void activate() throws SubscriptionException;</li>
* <li>public void cancel() throws SubscriptionException;</li>
* <li>public boolean isActive();</li>
* </ul>
* Subscription becomes active only after it is {@link #activate()}'d.
* <p>
* The life cycle of a subscription is:
* <ul>
*         <li> created (see parent interface {@link ISubscriptionSource}).
*         <li> event listeners added
*         <li> activated - only here actual subscription is sent to server and events may be generated.
*         <li> canceled
* </ul>
* <br>
*/
public interface IMarketScanSubscription<T> {

	/**
	 * Returns time frame for this subscription. For tick-based
	 * events this must return {@link TimeFrame#TIMEFRAME_1_TICK}.
	 * @return time frame.
	 */
	public TimeFrame getTimeFrame();

	/**
	 * returns the ScanCriteria for this subscription
	 * @return the subscribed ScanCriteria 
	 */
	public ScanCriteria getScanCriteria();

	/**
	 * Registers new event listener.
	 *
	 * @param listener event listener.
	 */
	public void addEventListener(IEventListener<T> listener);

	/**
	 * Removes event listener.
	 *
	 * @param listener event listener.
	 */
	public void removeEventListener(IEventListener<T> listener);

	/**
	 * Makes subscription active. No events may arrive before this
	 * method is called.
	 */
	public void activate() throws SubscriptionException;

	/**
	 * Cancels subscription. This makes subscription object no longer usable.
	 */
	public void cancel() throws SubscriptionException;

	/**
	 * Checks whether this subscription is active or not. Subscription is not active
	 * before first call to {@link #activate()}, and after first call to {@link #cancel()}.
	 *
	 * @return true if active.
	 */
	public boolean isActive();
}